Skip to content

Say when the API check runs and who sees the console alert - #37

Merged
dmccoystephenson merged 1 commit into
mainfrom
feature/docs-build-check-scope
Nov 4, 2026
Merged

dmccoystephenson merged 1 commit into
mainfrom
feature/docs-build-check-scope

Conversation

@dmccoystephenson

Copy link
Copy Markdown
Member

Summary

A Stage A documentation sweep compared every doc against Main.java, plugin.yml, pom.xml, the tests and the three workflows. Four inaccuracies were found and fixed:

  • API check scope (README.md, CONTRIBUTING.md). The README said "every build" checks Bukkit API use. Only build.yml runs that step; mvn clean package, dev-release.yml and release.yml do not. A contributor with a green local build could therefore still fail it on a pull request, and CONTRIBUTING.md now says so.
  • Build trigger (README.md). "Every push and pull request" is now "every push to main and every pull request against it", matching on: in build.yml.
  • Manual dev republish (README.md). dev-release.yml also has a workflow_dispatch trigger, used on 2026-10-25, 10-30 and 10-31. This is why the dev tag currently sits on docs-only commit 4997c96, which the README's push rule alone cannot explain.
  • Console alert (USER_GUIDE.md, COMMANDS.md, CHANGELOG.md). Main.java sends Alert: Can't be used by console. when !(sender instanceof Player), so command blocks and other non-player senders receive it too.

No tracking issue — gaps found during triage.

Validation

No code, manifest or workflow files are changed.

  • mvn -q -B clean package produced target/FlyCommand-1.0.1.jar; surefire reported Tests run: 4, Failures: 0, Errors: 0 (FlyCommandTest) and Tests run: 3, Failures: 0, Errors: 0 (PluginManifestTest). Those tests cover nothing in this diff; they only confirm that the tree is unchanged in behaviour.
  • The trigger and step claims were read directly from build.yml and dev-release.yml; the manual runs were read from gh run list --workflow dev-release.yml.
  • The non-player claim was traced through Main.java. It was not exercised with a real command block on a server.
  • .md files are in dev-release.yml's paths-ignore, so this merge does not republish dev.

Sweep results not changed here

  • The Issues link filtered on label:bug in the README could not be checked, because the label listing was not available in this session.
  • The README's statement that each stable release is booted on every supported version describes release automation outside this repository, so it could not be checked from here.

Skipped issues

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code


drafted by Claude on behalf of Daniel Stephenson

The README said every build checks Bukkit API use, but only the Build
workflow does: mvn clean package, Dev Release and Release do not. It
also said Build runs on every push, not just pushes to main, and left
out the manual trigger that has republished dev three times since #30.

The console alert is sent to any sender that is not a Player, so the
user guide and command reference now say so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dmccoystephenson

Copy link
Copy Markdown
Member Author

Self-review rubric, performed inline in a headless dispatch. This is not an independent review. A Copilot review could not be requested (Could not resolve user with login 'copilot'), so no external reviewer has seen this PR.

  • Scope: PASS — git diff --name-only origin/main...HEAD lists only CHANGELOG.md, COMMANDS.md, CONTRIBUTING.md, README.md and USER_GUIDE.md; every changed line belongs to one of the four corrections.
  • Validation-new: PASS — each claim was checked against its source. The API check appears only in build.yml; pom.xml has no such step; dev-release.yml declares workflow_dispatch, and gh run list shows three such runs; Main.java line 23 tests !(sender instanceof Player).
  • Validation-fix: PASS with one limit — FlyCommandTest.consoleIsRefused passes a plain CommandSender, not a ConsoleCommandSender, so the alert for any non-player sender is exercised by a test. A real command block was not tried on a server, and no recipe is required because behaviour is unchanged.
  • Sibling structure: PASS — no new files.
  • Sibling renames: PASS — nothing was renamed.
  • Docs: PASS — the console wording changed in both USER_GUIDE.md and COMMANDS.md, and the trigger wording in both README.md and CONTRIBUTING.md. README.md:85 (manual validation step 7) still tests the console only, which remains correct as a test step.
  • Issue resolution: not applicable — no Closes reference; the PR states that the gaps were found during triage.
  • Automated validation: PASS — the build check passed on this head (run 41788369910), which compiles, runs the tests and runs the API check. Locally mvn -q -B clean package reported 4 and 3 tests with 0 failures and 0 errors. These cover the unchanged code, not the wording.
  • Manifest declaration: PASS — FlyCommand.fly is at src/main/resources/plugin.yml:12; plugin.yml parses with PyYAML.
  • Command declaration: PASS — equalsIgnoreCase("fly") at Main.java:22 matches the Fly key at plugin.yml:7.
  • Main-class resolution: PASS — main: me.Daniel.FlyCommand.Main agrees with package me.Daniel.FlyCommand; and public class Main.
  • Override annotations: not touched by this PR.
  • No stack change: PASS — no build file or dependency is in the diff.
  • Changelog: PASS — a bullet was added under ## [Unreleased] / ### Fixed for the user-facing console correction. The contributor-facing README and CONTRIBUTING wording has no bullet, following State exactly which pushes republish the dev prerelease #33 and Say how the fly permission is granted in CONFIG.md #34, which also had none.
  • No harness leakage: PASS — the diff lists no .claude/ path.

Judgment call: the CONTRIBUTING.md sentence is long, but the addition is what warns contributors that a green local build does not cover the API check, so it was kept. Do-not-auto-merge paths: none matched.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).


drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson
dmccoystephenson merged commit 7682da8 into main Nov 4, 2026
1 check passed
@dmccoystephenson
dmccoystephenson deleted the feature/docs-build-check-scope branch November 4, 2026 06:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant